package org.jeecg.access.platform.service;

import org.jeecg.access.entity.PlatformAccount;

import java.util.List;

/**
 * @description: 同步用户数据并校验是否成功
 * @author: taogang
 * @date: 2025/7/31 10:11
 */
/**
 * 平台处理器接口，定义了对接外部平台的核心操作规范。
 * <p>
 * 该接口为不同外部平台（如社交媒体、第三方服务等）提供统一的处理标准，
 * 包括数据获取、账号识别、验证及同步等功能，通过实现此接口可实现多平台的适配。
 * </p>
 */
public interface PlatformHandler {

    /**
     * 获取当前处理器对应的平台类型标识。
     * <p>
     * 用于区分不同的外部平台（如"wechat"、"xhs"、"douyin"等），
     * 通常与系统中定义的平台类型常量对应，便于服务注册和路由。
     * </p>
     *
     * @return 平台类型字符串（非空，建议使用枚举值或常量）
     */
    String getPlatformType();

    /**
     * 从外部平台获取原始数据。
     * <p>
     * 具体实现可能包括调用外部API、解析接口响应等操作，返回的数据格式由平台决定，
     * 通常为JSON解析后的Java对象（如List、Map或自定义DTO）。
     * </p>
     *
     * @return 外部平台数据列表（可能为空，需根据平台实际返回处理）
     */
    List<?> fetchExternalData() ;

    /**
     * 从外部平台的原始数据中提取账号唯一标识。
     * <p>
     * 每个平台的账号标识字段可能不同（如"user_id"、"openid"等），此方法用于统一提取，
     * 便于系统对账号进行唯一性识别和管理。
     * </p>
     *
     * @param data 外部平台返回的单条原始数据（非空，类型与{@link #fetchExternalData()}返回的元素一致）
     * @return 账号唯一标识字符串（非空，如平台用户ID）
     */
    String extractAccountId(Object data);

    /**
     * 验证平台账号的有效性或合法性。
     * <p>
     * 可根据业务需求实现验证逻辑，例如校验账号状态是否正常、权限是否满足、
     * 数据是否完整等，返回结果将影响后续的同步操作。
     * </p>
     *
     * @param account 待验证的平台账号对象（非空，包含账号基本信息及关联数据）
     * @return 验证通过返回true，否则返回false
     */
    boolean verifyAccount(PlatformAccount account);

    /**
     * 将平台账号数据写入（同步）到外部系统。
     * <p>
     * 实现向外部平台推送账号信息的逻辑，可能包括调用创建/更新接口、处理返回结果等，
     * 通常在账号验证通过后执行。
     * </p>
     *
     * @param account 待同步的平台账号对象（非空，经过验证的有效账号）
     */
    void writeToExternalSystem(PlatformAccount account);


    String verifyAddedAccount(PlatformAccount account);
}
